home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 8: LINUX Games / Linux Cubed Series 8 - LINUX Games.iso / games / x11 / rpg / crossfir.92 / crossfir / crossfire-0.92.5 / doc / programming_guide < prev    next >
Text File  |  1996-07-24  |  7KB  |  146 lines
  1. This file is to hopefully detail some of programming guidelines that
  2. people should use when working on crossfire.
  3.  
  4. function names:  No real standard, but functions that work on commonly
  5. used structures typically use the following:  ob for object structure,
  6. map for map structure, and arch for archetype.  Thus, functions like
  7. insert_ob_in_map inserts an object into the map (both passed as
  8. arguments to the function.)
  9.  
  10. variable names:  Once again, no real standard.  In general, try to be
  11. descriptive and brief.  op is typically used for object (op = object
  12. pointer?) and pl is used for players.
  13.  
  14. Indentation:  The orignally standard seemed to be 2 spaces for nested
  15. level.  I personally prefer 4: with 2 spaces, it can be difficult to see
  16. how deeply nested something is.
  17.  
  18. #ifdef and configurable options:  This is only really needed if the option
  19. may not be desirable for all users.  Cases where things should be
  20. configuration options is when they use non standard libraries (XPM as one
  21. example) or make great and major changes that can be isolated in just a few
  22. #ifdefs.  This is a real grey area of what should and should not be a
  23. configurable option.  If not sure, send me mail and hopefully I can give you
  24. a definitive answer on a case by case basis.
  25.  
  26. If putting in LOG error messages, it is nice to put in the function
  27. name that the error is occuring in.  Since errors, by definition, should
  28. not be happening, it means that the code needs to be fixed or changed,
  29. and finding out the function where the error occurred makes things easier.
  30.  
  31. When putting LOG debug messages in your, code, #ifdef with a
  32. local define (ie, #ifdef INPUT_DEBUG or #ifdef TREASURE_DEBUG).  Don't use
  33. the generic DEBUG variable -- If everyone uses that, it just creates to much
  34. output, and becomes meaningless.  Using local defines makes it easy to turn
  35. on debugging information on that area of code, or likewise, turn it off, if
  36. it appears to work correctly.
  37.  
  38. When adding new fields to structures, use the [s/u]int[8/16/32] types.
  39. These types are meant to be at least that number of bits specified after
  40. the int, while 's' means signed, and 'u' unsigned.  Using these types
  41. will make porting to other systems easier, and for systems that may
  42. have large default values (64 bit ints), the typedefs can be changed so
  43. that uint32 is still 32 bits, and thus save memory.  This is especially
  44. necessary if you are using 8 bit types (normally char's) to store non
  45. character data.  The signedness of char's is not standard.  Thus, if you are
  46. assuming it is signed, and storing negative values, things may not work
  47. properly when it is unsigned.
  48.  
  49. For functions, using these values is not required, unless you need to make
  50. sure you have at least that precision.  A lot of functions just use
  51. ints for the value in for loops - this value is never likely to so
  52. large that using a special type is needed.
  53.  
  54. For strings, just use the native 'char' type.  Using sint8 or uint8
  55. probably will not work - at least not on all systems.  Plus, there is
  56. no reason to use those types for strings.
  57.  
  58. Other notes:
  59. Comments around code changes is also nice.  In many cases, why a change is
  60. being made is not readily apparent, and in these cases, I may not make the
  61. change.
  62.  
  63. Do not use the same name for function parameters as are typedef's.  Thus,
  64. things like char foo (int spell) should not be used, because spell is a
  65. typedef type.  This is apparantly illegal via ANSI standard, but I guess
  66. most compilers don't check for it.
  67.  
  68. ------------------------------------------------------------------------------
  69. PATCHES:
  70.  
  71. I prefer patches on a subject basis.  Thus, if you fix up some spell code,
  72. just send that along as a single patch.  Don't make jumbo patches that fixes
  73. half a dozen unrelated things.  It makes it more difficult for me on what is
  74. being changed and why.
  75.  
  76.  
  77. Patches can be submitted that fix bugs or that add additional features
  78. or otherwise improve the game.  Here are some hints for creating patches
  79. if you do not know how.
  80.   
  81.  
  82. If you have added new features to the game, or fixed a bug, I am interested
  83. in the patches.  Please following the coding guidelines listed above.
  84.  
  85. To make patches, make a diff file of the changes.  Try to only make a diff
  86. file of the pertinent files (ie, I don't need to see all the changes you
  87. might have made to your config.h file, unless you add new options.)  Make a
  88. context diff.  5 lines of context if preferable to the 3 default lines.  To
  89. do this, do:
  90.  
  91.    'diff -c5 (oldfile) (newfile)'
  92.  
  93. You can also do diffs of entire directories.  Do do this, type:
  94.  
  95. 'diff -c5 -r (old_directory) (new_directory)'
  96.  
  97. An example:
  98.  
  99. 'diff -c5 -r crossfire-0.90.1 crossfire-0.90.2'. 
  100.  
  101. This will create a context diff of all the changes made between version 90.1
  102. and 90.2.  Note that this will not include new files, but will include a
  103. message saying that a file exists in one version and not the other.  Also
  104. note that if you do a diff at the top level, diffs will be created for the
  105. various font and archetype files in the lib directory, greatly increasing
  106. the size, and not containing any useful information.
  107.  
  108. Note that some diff programs (Gnu diff for one) will put new files
  109. into patch archives.  You may need to give special command line options to
  110. do this.
  111.  
  112.  Please make sure that the actually directory the file is in included (ie,
  113. common, server, etc.)
  114.  
  115. To send new files (archetypes, or source files), shar archives, or
  116. uuencode tar archives (compressed or gzip'd is fine), are the preferred
  117. method.  IF you have an ftp site available to you, you can put the
  118. files up there instead of mailing them to me, but for smaller
  119. changes, mail is easier for me.
  120.  
  121. Mail all patches to mwedel@pyramid.com
  122.  
  123. ------------------------------------------------------------------------------
  124. Special notes:
  125.  
  126. Some elements in some of the structures should seldom be accessed
  127. directory.  If this was C++, they would probably be private members, with
  128. member functions to get the data.  The following will try to document them:
  129.  
  130. object->owner: Should never be access directly - get_owner and set_owner
  131. should be used instead.  Those functions set/check refcounts.  What this
  132. means is that if you do a get_owner and the owner has disappeared, you will
  133. get back a null pointer, instead of whatever object is now using that
  134. address (remember that objects get recycled.)
  135.  
  136. object->nrof: decrease_ob_nr should be used when decreasing the value
  137. (increasing should be done by inserting a new object with a count, and the
  138. insert function will merge them together.)  The reason decrease_ob_nr should
  139. be used is to handle weight properly - if this value is just decreased and
  140. is in some inventory, the weight will not be updated properly.  If it is
  141. situation when it is known that the object is 'removed', then adjustments to
  142. this variable are fine.
  143.  
  144.   Mark Wedel
  145. mwedel@pyramid.com
  146.